=======================
HeapAgent working model
=======================

HeapAgent is an interactive tool for debugging memory errors.  Unlike other 
tools, HeapAgent both detects memory errors AND includes tools for pinpointing 
the cause of each bug.  This demo is actually a fully functional copy of 
HeapAgent.  Its only limitation is that it is configured such that it can only 
be used to debug the included qsort sample application.

HeapAgent has a number advantages over other heap-debugging tools:

*  HeapAgent detects the broadest range of memory bugs in Windows 
   applications, including overwrites beyond the end of allocated blocks, 
   underwrites before the beginning of allocated blocks, wild overwrites, 
   overwrites over internal heap structures, leaks, double-frees, premature 
   frees, retained references to reallocated memory, references to data in 
   free allocations, writes into freed allocations, unexpected resizing of 
   allocations, invalid parameters to heap-related calls, and references to 
   data in uninitialized allocations.

*  HeapAgent reports more information about each error.  In addition to 
   reporting the file and line, HeapAgent provides a sequentially assigned 
   allocation number, the contents and address of each allocated object, and 
   most importantly, a pass count.  For source lines that allocate more than 
   one object, the pass count tells you which pass of the line allocated a 
   given object.  This ties the error to a specific allocation, rather than to 
   a less-meaningful source line that might have allocated hundreds of 
   objects.

*  HeapAgent includes interactive links to all heap-related aspects of any 
   error. From an error report, you can immediately browse the allocations and 
   their parameters, the heap contents, and the source code related to that 
   error.  This functionality is particularly valuable for overwrites, where, 
   for example, HeapAgent automatically highlights the overwritten memory in 
   a heap dump, and then lets you format the memory in meaningful types, and 
   display both the source that allocated it and its declared size. 

*  HeapAgent provides powerful debugging "heap-event agents" to help you 
   investigate the state of your program at strategic heap events.  Agents are 
   somewhat analogous to setting breakpoints in source code but are 
   specialized for finding the cause of heap errors.  For example, you may 
   have an object that is leaking, but you don't know where in your program 
   the object is used.  So you set an agent to break precisely as that object 
   is allocated -- from this break you can then click over to your debugger to 
   investigate the call stack leading up to this allocation.  Likewise, you 
   may have detected an allocation that is being double-freed but you don't 
   know the location of both frees.  So you simply set an agent to break every 
   time that allocation is freed, and then investigate the source at both 
   locations to determine which is incorrect.


More about the HeapAgent working model
--------------------------------------

The HeapAgent working model consists of a simple sorting application, QSort 
(QuickSort).  You can run QSort from Microsoft Visual C++ or Borland C++ for 
16-bit or 32-bit Windows.  This sample application reads all of the words 
in a text file, sorts them into alphabetical order, and saves the sorted list 
in another text file.  While QSort performs several sorts, HeapAgent detects 
an overwrite, a double-free, and two leaked objects.  The help file 
(ha_demo.hlp) included with this working model walks you through using 
HeapAgent to pinpoint the precise cause of each error.

Installing and running the HeapAgent working model
--------------------------------------------------

For information on installing and running the HeapAgent working model, 
see the file install.txt.